<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
   <TITLE>TKGate User Documentation (Options)</TITLE>
   <link rel="stylesheet" href="tkgate.css" type="text/css">
</HEAD>
<BODY>

<A NAME="options"></A>
<H2>8. Setting TkGate Options</H2>

TKGate has several user configurable parameters that can be set by
selecting "Options..." under the "File" menu. The options are divided
into nine main tabs.  Option settings are persistent, being saved in
the file ".tkgate2-preferences" in the user's home directory which is
read whenever starting TkGate.
<p>

<a name=general>
<h3>8.1 General Options</h3>

<div style="float: right; margin-left: 10;">
<a href="fig/generalOpts.gif">
<IMG SRC="fig/small-generalOpts.gif">
<br>
(Click to enlarge)</a>
</div>

These options control the general behavior of TkGate.  The options
that can be set through this page are:
<ul>
<li><b>Site Name:</b> Indicates the name of the organization where this
copy of TkGate is installed.  This string will be used on any reports
generated by TkGate.

<li><b>User Name:</b> Indicates the name of the TkGate user.  This name
will be used as the circuit creator name on reports generated by TkGate.

<li><b>Do safe file saving:</b> If enabled, TkGate will use a
multi-stage file saving technique to protect the integrity of save
files.  When saving, TkGate will first save to a temporary file in the
same directory as the file being saved.  It will then reread that file
checking for file inconsistencies.  If no inconsistencies are found, it
will then rename the temporary file to the target save file.  When this
option is disabled, the save will occur directly to the target save
file with no consistency checks.

<li><b>Include cells in save files:</b> If this option is enabled,
Verilog modules for TkGate's primitive cells such as AND gates and OR
gates will be included in the save file.  These cells are not needed
by TkGate, but any external simulation or synthesis tool may need
these cells in order to interpret the TkGate save files.

<li><b>Wire drop port creation:</b> If this option is enabled, ports
may be added to modules in edit mode by dropping a wire on the edge of
the block.  This was the standard port creation method in TkGate 1.8.
As of TkGate 2.0, there is a separate editor for module interface
creation and thus this feature is no longer needed. 

<li><b>Do Check-pointing/Frequency:</b> This option enables periodic
check-pointing of unsaved files.  The checkpoint file will have the
same base name as the file you are editing surrounded by '#' characters.
It will be saved in the current directory.  The frequency specifies a
time interval between checkpoints in seconds.

<li><b>Max Undo:</b> This option specifies the maximum number of operations
that can be undone using the undo/redo feature.

<li><b>Enable Help Balloons:</b> Causes help messages to be displayed
when the mouse cursor is over certain user interface elements.

</ul>
<br style="clear: right;">

<a name="interface">
<h3>8.2 Interface Options</h3>

<div style="float: right; margin-left: 10;">
<a href="fig/interfaceOpts.gif">
<IMG SRC="fig/small-interfaceOpts.gif">
<br>
(Click to enlarge)</a>
</div>

These options control features of the TkGate interface.  The options
that can be set through this page are:

<ul>
<li><b>Key Binding Style:</b> Indicates the basic style for
key-bindings.  Selecting "emacs" will result in key bindings that are
similar to Emacs (e.g., "Ctrl-x Ctrl-s" to save the current file).
Selecting "windows" will result in key bindings that are similar to
windows (e.g., "Ctrl-s" to save the current file).  Selecting "none"
will disabled all default bindings.  Bindings to not take effect until
restarting TkGate.

<li><b>Smooth Scrolling:</b> If this option is enabled, scrolling in
the main window will be performed using bitmap copies rather than by
using redisplays significantly improving scrolling performance.  If
your X server has problems with bitmap copies, you can disable this
feature.

<li><b>Region Update:</b> Controls the screen redraw algorithm.
Enabling this option will cause redraw events to redraw only the
portion of the screen which changes rather than the whole screen.
Normally this option should be left enabled, but on X servers with
poor clipping implementations, enabling this feature may actually
result in slower redrawing.

<li><b>Show side-bar images in dialog boxes:</b> Most dialog boxes
have side-bars on the left-hand side with an explanation of that
dialog box.  Unchecking this option will suppress these explanatory
messages resulting in slightly smaller dialog boxes.

<li><b>Font Set:</b> This option controls the overall size of the
fonts used in the user-interface.  Choose between "small", "normal",
"large" and "huge".
</ul>
<br style="clear: right;">

<a name="toolbar">
<h3>8.3 Toolbar Options</h3>

<div style="float: right; margin-left: 10;">
<a href="fig/toolbarOpts.gif">
<IMG SRC="fig/small-toolbarOpts.gif">
<br>
(Click to enlarge)</a>
</div>

These options control which toolbars will be available.  The options
that can be set through this page are:

<ul>
<li><b>Core Editor Toolbars:</b> These are toolbars that are
persistent through all modes or are used in circuit edit mode.

<li><b>Simulation Mode Toolbars:</b>  These are toolbars that
are available only while the simulator is active.

<li><b>Symbol Editor Toolbars:</b>  These are toolbars that
are available only when the symbol editor is active. 
</ul>

<br style="clear: right;">

<a name=hdl>
<h3>8.4 HDL Options</h3>

<div style="float: right; margin-left: 10;">
<a href="fig/hdlOpts.gif">
<IMG SRC="fig/small-hdlOpts.gif">
<br>
(Click to enlarge)</a>
</div>

These options control the behavior of TkGate when editing text HDL
modules.  The options that can be set through this page are:
<ul>

<li><b>Enable drag-and-drop of selection:</b> When this option is
enabled, you can select a block of text with the mouse and drag it to
a new location.

<li><b>Enabled Automatic Indenting:</b> When this option is enabled,
TkGate will do automatic indentation of the HDL text.  When enabled,
the following additional indenting options can be set:
<ul>

<li><b>Indentation per level:</b> This specifies the number of
characters to indent for each level of scope in the Verilog module.

<li><b>Make begin..end flush with enclosing level:</b> If this feature
is enabled, any "begin..end" blocks will be indented the same amount
as the statement that encloses it (e.g., the parent "if" statement).

<li><b>Auto indent after return:</b> If this feature is enabled,
TkGate will fix formatting each time you press return.
</ul>

<li><b>Enabled Code Colorization:</b> If this feature is enabled, the
Verilog text will be colorized based in its semantic meaning.  You can
choose the color, and whether the text should be in bold or italics. 
</ul>

<br style="clear: right;">

<a name=print>
<h3>8.5 Print Options</h3>

<div style="float: right; margin-left: 10;">
<a href="fig/printOpts.gif">
<IMG SRC="fig/small-printOpts.gif">
<br>
(Click to enlarge)</a>
</div>

These options control the default printing behavior of TkGate.  The
options that can be set through this page are:

<ul>
<li><b>Printer:</b> Specifies the printer to use when printing
circuits or traces.  TkGate will scan the /etc/printcap files to
extract the list of available printers.  A "Default Printer" will
also be included in the list.  The "Advanced..." button can be used
to edit the printer command that is associated with that printer.

<li><b>Paper Size:</b> Indicates the paper size of the document.  If
your printer is multi-tray, the appropriate tray will be selected.  A
variety of U.S. and European/Asian paper sizes are provided.

<li><b>Orientation:</b> Indicates the orientation of the diagram on
the page.  If you select "Portrait", the image will be printed so
that the long side of the paper is vertical.  If you select
"Landscape", the image will be printed so that the short side is
vertical.

<li><b>Print Double-Sided:</b> Indicates that images should be printed
on both sides of the page.&nbsp;  This option is only effective on printers
capable of double-sided printing.

<li><b>Scale large modules to fit page:</b> Modules which cannot fit
on a single page without scaling will be reduced in size so they
fit.

<li><b>Partition large modules into multiple pages:</b>Modules which
cannot fit on a single page without scaling will be split into
multiple pages.  A key indicating which portion a page represents will
be printed in the lower right corner of the page.

<li><b>Include index:</b> Prints an index page listing each of the modules
in alphabetical order and the pages they are on.

<li><b>Include hierarchy graph:</b> Prints a hierarchy graph rooted at
the top-level module showing the relationship between parent and child
modules.

<li><b>Print small modules four per page:</b> Causes modules which can
fit into a single quadrant to be grouped and printed on the same page.
</ul>
<br style="clear: right;">

<a name=simulate>
<h3>8.6 Simulate Options</h3>

<div style="float: right; margin-left: 10;">
<a href="fig/simulateOpts.gif">
<IMG SRC="fig/small-simulateOpts.gif">
<br>
(Click to enlarge)</a>
</div>

These options control the simulation behavior of TkGate.  The
options that can be set through this page are:

<ul>

<li><b>Epoch Step Size:</b> Specifies the default number of epochs to
advance the simulator each time the space bar is pressed.

<li><b>Clock Overstep:</b> Specifies the default number of epochs to
advance since a clock event when stepping by clock cycles.

<li><b>Clock Cycle Step Size:</b> Specifies the number of clock cycles
to advance when pressing the Tab key.

<li><b>Pop-Up Delay:</b> Specifies the default number of milliseconds
to wait before showing the value of a signal when clicking on it.

<li><b>Sort traces alphabetically on scope:</b> If enabled, traces in
the scope are sorted alphabetically.  If not enabled, the traces are
listed in the order in which probes were set.

<li><b>Enable simulator glitch suppression:</b> Enables a simulation
feature that suppresses very fast changes on a signal.  When this
option is on, oscillations on a gate input faster than that gate's
delay will produce "unknown" on the output rather than propagating the
oscillations.

<li><b>Technology Files:</b> Use this to install additional
user-defined delay/area models for gates in addition to the built-in
model.  Gate delay files have a ".gdf" extension.

<li><b>Error Handling:</b> Use this feature to tell TkGate what to do
with simulator errors and warnings. One of the following levels can be
selected:

<ul>
<li><b>Cancel simulation on any warnings:</b> If there are any warning
messages about the current circuit, do not allow the simulation to start.

<li><b>Always display warnings:</b> If there are any warning messages
about the current circuit, display the warnings, but let the
simulation start.

<li><b>Display warnings only with errors:</b>If there are any warning
messages about the current circuit but there are no error messages, do
not display the warnings and let the simulation start.  If there are
error messages, the warnings will be displayed along with them.

<li><b>Ignore all warnings:</b>Ignore and do not display any warning
messages.  Only error messages will be displayed.
</ul>

</ul>

<br style="clear: right;">

<a name=library>
<h3>8.7 Library Options</h3>

<div style="float: right; margin-left: 10;">
<a href="fig/librariesOpts.gif">
<IMG SRC="fig/small-librariesOpts.gif">
<br>
(Click to enlarge)</a>
</div>

These options control where TkGate looks for libraries and which
libraries should be automatically loaded on start-up.  The options
that can be set through this page are:
<ul>

<li><b>Verilog Library Path:</b> Specifies the list of directories in
which to search for Verilog library files.  The string
"${TKGATE_HOME}" is replaced with the TkGate home directory.

<li><b>Base Libraries:</b> Specifies the list of libraries that should
be loaded by TkGate on start-up, irregardless of the circuit that is
being loaded.  Circuit-specific libraries should be specified in the
Circuit Properties dialog box.

<li><b>VPD (Virtual Peripheral Device) File Path:</b> Specifies the
list of directories in which to search for virtual peripheral device
files.  Virtual peripheral device files have a ".tcl" extension and
contain Tcl code conforming to TkGate's VPD protocol.
</ul>

<br style="clear: right;">

<a name=security>
<h3>8.8 Security Options</h3>

<div style="float: right; margin-left: 10;">
<a href="fig/securityOpts.gif">
<IMG SRC="fig/small-securityOpts.gif">
<br>
(Click to enlarge)</a>
</div>

These options control simulator features such as VPDs (Virtual
Peripheral Devices) that have potential security implications.  Set
these carefully when simulating an unknown or untrusted circuit.
<ul>

<li><b>Enable the $tkg$command() system task:</b> If enabled, user
circuits can use the $tkg$command().  This system task can send a
low-level command directly from the simulator to the TkGate interface.
For normal circuits, there is seldom a reason to enable this feature.

<li><b>Enable the $fopen() system task:</b> If enabled, user circuits
can use the $fopen() system task to open arbitrary files in the user's
directory for read and write.  This can be useful for debugging
circuits, but should not be enabled for untrusted circuits.

<li><b>Enable the $writememb() and $writememh() system tasks:</b> If
enabled, user circuits can use the $writememb() and $writememh()
system tasks to write the contents of a memory to an arbitrary files
in the user's directory.  This can be useful for debugging
circuits, but should not be enabled for untrusted circuits.

<li><b>Enable the $tkg$recv() and $tkg$send() system tasks:</b> If
enabled, user circuits can use the $tkg$recv() and $tkg$send() system
tasks.  These are necessary for VPDs (Virtual Peripheral Devices) to
work properly.

<li><b>The $tkg$exec() system task is:</b> The $tkg$exec() system
tasks allows a user to execute an arbitrary Tcl/Tk command in the
context of TkGate. Indirectly this could cause an arbitrary shell
command to be executed.  Some VPD implementations use this mechanism
to pass data between the Verilog portion and the Tcl portion.  One of
the following security settings can be used for this task. 
<ul>

<li><b>fully enabled:</b> Allows unrestricted use of the $tkg$exec()
task.  This setting is not recommended.

<li><b>enabled only for registered functions:</b> Allows only
functions that have been registered as safe or necessary for a VPD to
be executed.  The '[' and ']' characters are disallowed when this
setting is selected.

<li><b>disabled:</b> The $tkg$exec() task is completely disabled and
can not be used from user circuits.
</ul>

<li><b>Security Violation Handling:</b> This option specifies what
TkGate should do when a user circuit tries to use a system task that
has been disabled through this dialog box.

<li><b>Stop simulator when disabled feature is used:</b> Any attempted use of a
disabled system task will cause the simulator to stop and a warning
message to be displayed.

<li><b>Display warning message when disabled feature is used:</b> Any
use of a disabled system task will cause a warning message to be
displayed, but the simulation will continue to execute with the call
to the disabled task ignored.

<li><b>Ignore attempted usage of disabled features:</b> Any attempts
to use a disabled system task will be silently ignored.
</ul>

<br style="clear: right;">

<a name=color>
<h3>8.9 Color Options</h3>

<div style="float: right; margin-left: 10;">
<a href="fig/colorOpts.gif">
<IMG SRC="fig/small-colorOpts.gif">
<br>
(Click to enlarge)</a>
</div>

These options control the colors used for various elements in the
TkGate interface.  The options that can be set through this page are:
<ul>
<li><b>Edit Window Colors</b> These options specify the color of elements in the main editor window.
<ul>
<li><b>Background:</b> Sets background color for the editing canvas.
<li><b>Instances:</b> Sets the color used for primitive gates and their labels.
<li><b>Modules:</b> Sets the color used for modules, other than the port names.
<li><b>Module Ports:</b> Sets the color used for port names on modules.
<li><b>Frames:</b> Sets the color used for frames.
<li><b>Comments:</b> Sets the color used for normal comments.
<li><b>Hyperlinks:</b> Sets the color used for hyperlink comments.
<li><b>Single-Bit Wires:</b> Sets the color used for single-bit wires and their labels.
<li><b>Multi-Bit Wires:</b>  Sets the color used for multi-bit wires and their labels.
<li><b>Gate Tools:</b> Sets the color for other non-cursor objects used by TkGate (e.g., probes).
<li><b>Critical Path:</b> Sets the color used to highlight the critical path in the circuit.
<li><b>Off LED:</b> Sets the color for LEDs which are off.
<li><b>On LED:</b> Sets the color for LEDs which are on.
<li><b>Floating LED:</b> Sets the color for LEDs for which the input signal is a non 0/1 value.
in the logic scope.
</ul>

<li><b>Scope Window Colors</b>
<ul>
<li><b>Scope Grid:</b> Sets the color for the grid in the logic scope.
<li><b>Logic One:</b> Sets the color for all deterministic non-zero logic values in the logic scope.
<li><b>Logic Zero:</b> Sets the color for zero logic values in the logic scope.
<li><b>Float:</b> Sets the color for floating logic values in the logic scope.
<li><b>Unknown/Conflict:</b> Sets the color for unknown logic values, including the "low" and "high" values,
in the logic scope.
</ul>

<ul>
</ul>

</ul>
<br style="clear: right;">


<A NAME="html"></A>
<h3>8.10 HTML Options</h3>

<div style="float: right; margin-left: 10;">
<a href="fig/htmlOpts.gif">
<IMG SRC="fig/small-htmlOpts.gif">
<br>
(Click to enlarge)</a>
</div>

These options control what TkGate should do when the user clicks on
certain hyperlinks in their circuit.
<ul>

<li><b>Browser Command:</b> Specifies the command to use when the user
clicks on a hyperlink starting with "http:".  Normally this should
point to the user's browser command.  A "%s" in the command will be
replaced with the text of the hyperlink the user clicked on.

<li><b>e-Mail Command:</b> Specifies the command to use when the user
clicks on a hyperlink starting with "mail:".  Normally this should
point to the user's e-mail client.  A "%s" in the command will be
replaced with the text of the hyperlink the user clicked on.
</ul>

<br style="clear: right;">
